Création de transactions par voie programmatique OneSpan Sign
OneSpan Sign pour Salesforce vous permet de créer des transactions OneSpan Sign de manière programmatique. Il y a deux façons principales de le faire :
- Création d'une transaction à partir d'un bouton personnalisé
- Création d'une transaction à partir d'une action personnalisée
La section suivante fournit des informations relatives aux deux procédures ci-dessus :
L'URL qui apparaît dans les exemples de code ci-dessous doit commencer par la chaîne de caractères /apex/esl__package?
. Il s'agit de l'URL requise pour accéder à la page Visualforce d'une transaction à OneSpan Sign.
Création d'une transaction à partir d'un bouton personnalisé
Si vous créez un bouton personnalisé et l'ajoutez à un objet Salesforce, le bouton ajouté permet aux utilisateurs de Salesforce d'envoyer des documents à signer à partir des enregistrements de cet objet.
Vous pouvez créer une transaction à partir d'un bouton personnalisé de la manière suivante :
- Création d'une transaction à partir d'un modèle
- Création d'une transaction à partir d'un identifiant Salesforce ou d'une adresse courriel
- Création d'une transaction à partir d'une convention
Création d'une transaction à partir d'un modèle
Pour créer un paquet de manière programmatique à partir d'un modèle :
- Écrivez puis exécutez le code qui créera un paquet à partir d'un modèle.
Vous devez spécifier les paramètres de modèle suivants :
ParentId
Name
TemplateId
À la fin de cette procédure, vous devriez voir toutes les informations du modèle reflétées dans le paquet créé.
Exemple
Lorsque l'extrait de code suivant est exécuté, il crée un paquet OneSpan Sign à partir d'un modèle pour un compte particulier :
/apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&TemplateID=a0G360000018BdREAU
Création d'une transaction à partir d'un identifiant Salesforce ou d'une adresse courriel
Lorsque vous créez une transaction à partir d'un ID Salesforce, vous devez spécifier les paramètres suivants :
Name
SignerN
- Il peut s'agir d'un identifiant Salesforce (voir Exemple 1) ou d'une adresse courriel pour le Nième destinataire (voir Exemple 2). SiSignerN
est une adresse courriel, les paramètres suivants sont également requis :SignerNFirstName
SignerNLastName
Documents
- Portable Document Format d'Adobe (*.pdf) — Les PDF sur lesquels OneSpan Sign peut généralement agir ont au moins ces autorisations activées : (1) Modification du document ; (2) Signature ; (3) Remplissage des champs de formulaires.
- Microsoft Word (*.doc ou *.docx)
- Open Office (*.odt)
- Texte (*.txt)
- Rich Text Format (*.rtf)
- La taille maximale d'un document unique est de 16 Mo. Les documents plus petits offrent de meilleures performances. Nous recommandons moins de 5 Mo par document.
- Si votre organisation utilise les connecteurs Salesforce ou Microsoft SharePoint, la taille maximale des fichiers est de 5 Mo par document.
- Si votre organisation utilise les connecteurs Salesforce, le nombre maximum de documents qui peuvent être ajoutés à une transaction est de dix (10).
- Si vous activez la livraison par courriel lors de la configuration d'un destinataire, les pièces jointes de plus de 5 Mo ne sont pas prises en charge.
- Les noms de fichiers des documents ne doivent contenir aucun des caractères suivants, séparés par des virgules : *, /, \, :, <, >, |, ?, ".
- Le nom d'un document ne peut pas contenir la chaîne esigned.
- Nous vous recommandons de ne pas utiliser les documents PDF qui utilisent l'architecture des formulaires XML. Pour plus d'informations, voir Support XFA.
- Ne téléversez pas de documents protégés par un mot de passe ou corrompus. Ceux-ci génèrent une erreur.
- OneSpan recommande fortement de scanner un PDF pour détecter les erreurs de syntaxe (par exemple, en utilisant l'outil Preflight d'Adobe), et de résoudre toute erreur avant d'ajouter le document à une transaction.
- Les PDF dont l'indicateur NeedAppearances est défini sur true ne sont pas pris en charge actuellement.
OneSpan Sign prend en charge les types de documents suivants :
En outre, le pilote d'impressionOneSpan Sign prend en charge tout document pouvant être imprimé à partir d'une application Windows (p. ex. : Microsoft Word, Microsoft Excel, Microsoft PowerPoint).
Contraintes de taille des fichiers
Contraintes relatives aux noms de fichiers
Contraintes générales des fichiers
À la fin de cette procédure, vous devriez voir les informations fournies reflétées dans le paquet créé.
Exemple 1
Lorsque le bout de code suivant est exécuté, il crée un paquet OneSpan Sign à partir de l'ID d'un contact :
/apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&Signer1=00336000003gBYX&Documents=00P36000000wwrd
Exemple 2
Lorsque l'extrait de code suivant est exécuté, il crée un paquet OneSpan Sign à partir d'une adresse courriel. En particulier, cet extrait crée un destinataire de type External Email
avec l'adresse courriel [email protected]
.
/apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&[email protected]&Signer1FirstName=john&Signer1LastName=doe&Documents=00P36000000wwrd
Création d'une transaction à partir d'une convention
Création d'une transaction à partir d'une convention à l'aide d'un code personnalisé :
- Créez une convention appropriée. Pour obtenir plus d'informations, voir les Automatisation via des conventions OneSpan Sign.
- Créez un bouton personnalisé qui exécutera le code nécessaire lorsque le bouton sera cliqué (voir l'exemple ci-dessous).
- Cliquez sur le bouton Personnalisé. Cette opération devrait créer une transaction avec les informations spécifiées dans la convention.
Lorsque l'extrait de code suivant est exécuté, il crée une transaction OneSpan Sign à partir d'une Convention, où :
ConventionId
est l'ID de la convention à utiliser.Signer1Label
est l'ID de l'étiquette du destinataire à appliquer au signataire1
/apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&Documents=00P36000000wwrd&ConventionId=a0836000000nfRo&Signer1=00336000003gBYX&Signer1Label=a0K36000001j8VW
Création d'une transaction à partir d'une action personnalisée
Si vous créez une action personnalisée et l'ajoutez à un objet Salesforce, l'action ajoutée permet aux utilisateurs de Lightning Experience d'envoyer facilement des documents à signer via OneSpan Sign.
L'URL utilisée dans la procédure pour une action personnalisée est la même que celle d'un bouton personnalisé, sauf que l'URL d'une action personnalisée doit être stockée dans un champ personnalisé créé sur l'objet.
Pour créer une transaction par le biais d'une action personnalisée, procédez comme suit :
- Étape 1 : Créez un champ qui stockera l'URL d'automatisation.
- Étape 2 : Créez une page Visualforce pour déclencher l'automatisation.
- Étape 3 : Créez l'action dans le composant, et associez-lui la page Visualforce.
- Étape 4 : Ajoutez l'action à la mise en page.
Étape 1 : Créez un champ qui stockera l'URL d'automatisation.
Dans cette étape, vous devez créer un champ dans l'objet (compte, contact, opportunité, etc.) qui stockera l'URL d'automatisation. Cette URL suit les mêmes règles que pour le bouton personnalisé, et elle reçoit les mêmes paramètres.
Nous vous recommandons d'utiliser des champs de formule, afin de pouvoir utiliser des « fusionner les champs ».
<apex:page standardController="Account">
<ESL:PackageAutomation fieldName="Account_Automation_URL__c" />
</apex:page>
Étape 2 : Créez une page Visualforce pour déclencher l'automatisation.
Dans la page Visualforce, l'utilisateur Admin doit utiliser un composant fourni par le connecteur pour : (1) lire l'URL de l'automatisation stockée dans le champ créé ci-dessus; (2) déclencher l'automatisation.
Pour créer la page Visualforce :
- Cliquez sur Configuration.
- Dans le volet de gauche, cliquez sur Développer > pages Visualforce. Une liste de pages Visualforce apparaît.
- Cliquez sur Nouveau.
- Saisissez une étiquette, un nom et une description appropriés pour la nouvelle page.
- Cochez la case Disponible pour les applications mobiles Salesforce et les pages Lightning.
- Dans l'onglet Visualforce Markup, tapez le code suivant :
Après que l'utilisateur Admin ait créé la page Visualforce, il doit spécifier : (1) le nom de l'objet qui utilisera cette page (par exemple, Compte, Contact, Opportunité, un objet personnalisé, etc.); (2) le nom du champ où l'URL est stockée.
Étape 3 : Créez l'action dans le composant, et associez-lui la page Visualforce.
- Cliquez sur Configuration.
- Si vous souhaitez utiliser un objet standard, dans le volet de gauche, cliquez sur Personnaliser, puis sélectionnez l'objet.
- Si vous voulez utiliser un objet personnalisé :
- Dans le volet de gauche, cliquez sur Créer > Objets. Une nouvelle page affiche une liste d'objets personnalisés.
- Trouvez l'objet personnalisé concerné et cliquez sur son nom.
- Dans la section Boutons, liens et actions, cliquez sur Nouvelle action. La page Nouvelle action s'ouvre.
- Sous Type d'action, sélectionnez Visualforce personnalisé.
- Sous Page Visualforce, sélectionnez la page Visualforce que vous avez créée précédemment.
- Saisissez une étiquette et un nom appropriés pour la nouvelle action personnalisée.
- Cliquez sur Enregistrer.
Étape 4 : Ajoutez l'action à la mise en page.
Une fois l'action créée, l'utilisateur Admin doit l'ajouter à la mise en page pour la rendre accessible aux autres utilisateurs. Elle doit également être ajoutée aux actions Salesforce1 pour être disponible sur les appareils mobiles.
Pour ajouter la nouvelle action personnalisée à la mise en page de votre objet personnalisé :
- Cliquez sur Configuration.
- Dans le volet de gauche, cliquez sur Créer > Objets. Une nouvelle page affiche une liste d'objets personnalisés.
- Trouvez votre objet personnalisé, et cliquez sur son nom.
- Dans la section Mise en page, cliquez sur Modifier. La page Mise en page s'affiche.
- Cliquez sur l'option Mobile et Lightning dans le volet supérieur gauche.
- Si vous ne voyez aucune action dans la section Actions de l'expérience mobile et Lightning, cliquez sur l'icône de clé à molette qui apparaît lorsque vous passez votre souris sur cette section.
- Faites glisser la nouvelle action personnalisée dans la section Actions de l'expérience mobile et Lightning.
- Cliquez sur Enregistrer.
À la fin de cette procédure, vous devriez voir toutes les informations saisies reflétées dans la transaction créée.
Paramètres pour les vignettes de code d'URL
Le tableau suivant décrit les paramètres qui peuvent être utilisés dans les extraits de code URL pour toutes les procédures ci-dessus.
Un échantillon statique a une valeur fixe. La valeur d'un échantillon dynamique est spécifiée par un champ fusionné.
Nom du paramètre |
Description |
Échantillon statique |
Échantillon dynamique |
---|---|---|---|
IdModèle |
L'ID du modèle de la transaction. Si elle n'est pas fournie, créez-la de manière ad hoc. Tout champ spécifié dans l'URL remplacera la valeur du modèle. Le modèle doit être actif. |
|
|
Name |
Le nom de la transaction, codé en URL. |
|
|
Description |
La description de la transaction, codée en URL. |
|
|
ExpiryDate |
La date d'expiration de la transaction (AAAAMMJJ) |
|
|
EmailMessage |
Les valeurs saisies dans EmailMessage seront transmises aux modèles par défaut existants de l'espace réservé "$PACKAGE_MESSAGE ;", tels que le modèle "email.activate" et le modèle "email.notify". Pour plus d'informations, voir Développeurs OneSpan Sign : Modèles de courriels. |
|
|
Langue |
La langue du paquet de transactions. Les options disponibles sont basées sur les choix de langue effectués sur la page de personnalisation. |
|
|
InPersonSigning |
Indicateur qui spécifie si la signature en personne est vraie ou fausse |
|
|
Documents |
Liste d'identifiants séparés par des virgules. Ces identifiants peuvent correspondre aux pièces jointes Salesforce, aux documents Salesforce ou aux fichiers Salesforce. Créez une pièce jointe, un document ou un fichier de transaction avec son binaire, et avec un nom associé qui correspond à l'ordre de l'élément dans la liste. Remarque : les fichiers Salesforce ne sont pris en charge qu'à partir de OneSpan Sign Embedded Integration for Salesforce 4.10. Le système prend en charge un maximum de 5 Mo par document (les documents plus petits donnent de meilleures performances - nous recommandons moins de 5 Mo par document). Le système prend en charge un maximum de 10 documents par transaction ou modèle de transaction. Cependant, il n'y a pas de limite à la taille collective totale des documents dans une transaction. |
|
|
Send |
Indicateur qui indique si la transaction doit être envoyée après avoir été créée. Requiert une convention par défaut ou le paramètre conventionID, et une étiquette de destinataire pour au moins un des destinataires. |
|
|
ConventionId |
L'ID de la convention qui sera utilisé pour préparer et envoyer la transaction. ConventionId est obligatoire si aucune convention par défaut n'a été définie dans les paramètres personnalisés. |
|
|
retUrl |
L'URL vers laquelle les utilisateurs seront dirigés une fois la transaction envoyée. Elle doit avoir Send=1 ou Send=true, et doit être codée en URL. |
|
|
DescriptionObjectName |
Spécifie la description d'une transaction, en utilisant le nom d'un objet personnalisé. Il doit s'agir d'un nom d'objet comme Compte ou Transaction__c. Ce paramètre requiert DescriptionObjectField et DescriptionObjectId. |
|
|
DescriptionObjectField |
Spécifie la description d'une transaction, en utilisant un champ d'un objet personnalisé. Doit être un champ dans l'objet défini dans DescriptionObjectName, comme Name ou Description__c. Ce paramètre requiert DescriptionObjectName et DescriptionObjectId. |
|
|
DescriptionObjectId |
Spécifie la description d'une transaction, en utilisant l'ID d'un objet personnalisé. Doit être l'ID d'un objet du type défini dans DescriptionObjectName. Ce paramètre requiert DescriptionObjectName et DescriptionObjectField. |
|
|
EmailMessageObjectName |
Spécifie le courriel d'une transaction, en utilisant le nom d'un objet personnalisé. Doit être un nom d'objet comme Compte ou Transaction__c. Ce paramètre requiert EmailMessageObjectField et EmailMessageObjectId. |
|
|
EmailMessageObjectField |
Spécifie le message électronique d'une transaction, en utilisant un champ d'un objet personnalisé. Doit être un champ de l'objet défini dans EmailMessageObjectName, tel que le nom ou la description__c. Ce paramètre requiert EmailMessageObjectName et EmailMessageObjectId. |
|
|
EmailMessageObjectId |
Spécifie le message courriel d'une transaction, en utilisant l'ID d'un objet personnalisé. Doit être l'ID d'un objet du type défini dans EmailMessageObjectName. Ce paramètre requiert EmailMessageObjectName et EmailMessageObjectField. |
|
|
SignerX |
X est un nombre compris entre 1 et l'infini. La valeur peut être un identifiant de prospect, un identifiant de contact, un identifiant d'utilisateur ou une adresse courriel. Si une adresse courriel est fournie, les paramètres SignerXFirstName et SignerXLastName sont requis. |
|
|
SignerXFirstName |
Spécifie le prénom du destinataire à l'index X. Il n'est disponible que pour les destinataires externes du courriel. |
|
|
SignerXLastName |
Spécifie le nom de famille du destinataire à l'index X. Il n'est disponible que pour les destinataires externes du courriel. |
|
|
SignerXPhone |
Spécifie le numéro de téléphone du destinataire à l'index X. Il n'est disponible que pour les destinataires externes du courriel. |
|
|
SignerXLabel |
Spécifie l'étiquette du destinataire associée au destinataire à l'index X. Doit être l'ID de l'objet recipient-label dans la convention associée (la convention par défaut ou celle spécifiée dans ConventionId). |
|
|
SignerXAllowDelegation |
Ce paramètre détermine si vous autorisez le destinataire initial que vous avez identifié à déléguer une autre personne pour signer la transaction en son nom. Les valeurs valides sont : 1 ou 0, vrai ou faux. Si la valeur est 1 ou vrai, le destinataire sera invité à saisir l'adresse courriel et le nom complet du délégué, ainsi qu'un message courriel facultatif à envoyer au délégué. Vous serez informé de ce changement de destinataire, et serez mis en copie conforme sur le message courriel (s'il est envoyé). |
Signer1=003g000000OLhpk&Signer1AllowDelegation=true
|
Signer1={!Contact.Id}&Signer1AllowDelegation=1
|
SignerXAuthMethod |
Indicateur qui vous permet de créer une transaction automatiquement, en utilisant l'une des méthodes d'authentification suivantes :
Si la méthode d'authentification choisie est la question-réponse, les paramètres supplémentaires suivants doivent être configurés :
Notez que X est le nombre de destinataires et Y le nombre de questions (jusqu'à 2 questions sont prises en charge). |
Signer1=003g000000OLhpk&Signer1AuthMethod=sms
|
Signer1={!Contact.Id}&Signer1AuthMethod={!Contact.AuthenticationMethod__c}
|
AutoPrepare | Indicateur qui détermine si la fonction de préparation automatique sera activée pour une transaction si une convention est spécifiée. Les valeurs valides sont : 1 ou 0, vrai ou faux. | AutoPrepare=true
|
AutoPrepare={!Account.AutoPrepareTransaction__c} Insert={!Account.InsertValueInTransaction__c}
|
Insérer |
Indicateur qui détermine si les données de Salesforce seront auto-remplies dans un document OneSpan Sign lorsque la transaction du document est préparée. Les valeurs valides sont : 1 ou 0, vrai ou faux. |
Insert=true
|
Insert={!Account.InsertValueInTransaction__c}
|
Réécriture | Indicateur qui détermine si un champ Salesforce sera mis à jour avec les données d'un document OneSpan Sign lorsque la transaction de ce document sera terminée. Les valeurs valides sont : 1 ou 0, vrai ou faux. | WriteBack=true
|
WriteBack={!Account.WriteValueInTransaction__c}
|
EnforceSigningOrder |
Indicateur qui détermine si la condition d'application de l'ordre de signature est vraie ou fausse. |
|
|
ParentId |
ID de l'objet parent. À enregistrer dans le champ de texte ParentId. Il remplit automatiquement le type parent et le champ de recherche associé, si possible. |
|
|
enableReminders |
Indicateur (vrai/faux) qui détermine si la fonction de rappel automatique est activée pour la transaction. |
|
|
sendReminderDays |
Nombre de jours avant l'envoi du premier rappel. |
|
|
repeatReminderDays |
Intervalle en jours entre les rappels successifs. |
|
|
totalReminders |
Nombre maximum de rappels à envoyer. |
|
|
ChatterEnable |
Indicateur (vrai / faux) qui détermine si Chatter sera actif sur la transaction. |
|
|